/*
 * Copyright (c) 2002, 2008, Oracle and/or its affiliates. All rights reserved.
 * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 */

package javax.management.remote.rmi;

import java.io.Closeable;
import java.io.IOException;
import java.rmi.MarshalledObject;
import java.rmi.Remote;
import java.util.Set;

import javax.management.AttributeList;
import javax.management.AttributeNotFoundException;
import javax.management.InstanceAlreadyExistsException;
import javax.management.InstanceNotFoundException;
import javax.management.IntrospectionException;
import javax.management.InvalidAttributeValueException;
import javax.management.ListenerNotFoundException;
import javax.management.MBeanException;
import javax.management.MBeanInfo;
import javax.management.MBeanRegistrationException;
import javax.management.MBeanServerConnection;
import javax.management.NotCompliantMBeanException;

import javax.management.ObjectInstance;
import javax.management.ObjectName;
import javax.management.ReflectionException;
import javax.management.RuntimeMBeanException;
import javax.management.RuntimeOperationsException;
import javax.management.remote.NotificationResult;
import javax.security.auth.Subject;

/**
 * <p>RMI object used to forward an MBeanServer request from a client
 * to its MBeanServer implementation on the server side.  There is one
 * Remote object implementing this interface for each remote client
 * connected to an RMI connector.</p>
 *
 * <p>User code does not usually refer to this interface.  It is
 * specified as part of the public API so that different
 * implementations of that API will interoperate.</p>
 *
 * <p>To ensure that client parameters will be deserialized at the
 * server side with the correct classloader, client parameters such as
 * parameters used to invoke a method are wrapped in a {@link
 * MarshalledObject}.  An implementation of this interface must first
 * get the appropriate class loader for the operation and its target,
 * then deserialize the marshalled parameters with this classloader.
 * Except as noted, a parameter that is a
 * <code>MarshalledObject</code> or <code>MarshalledObject[]</code>
 * must not be null; the behavior is unspecified if it is.</p>
 *
 * <p>Class loading aspects are detailed in the
 * <a href="{@docRoot}/../technotes/guides/jmx/JMX_1_4_specification.pdf">
 * JMX Specification, version 1.4</a> PDF document.</p>
 *
 * <p>Most methods in this interface parallel methods in the {@link
 * MBeanServerConnection} interface.  Where an aspect of the behavior
 * of a method is not specified here, it is the same as in the
 * corresponding <code>MBeanServerConnection</code> method.
 *
 * @since 1.5
 */
/*
 * Notice that we omit the type parameter from MarshalledObject everywhere,
 * even though it would add useful information to the documentation.  The
 * reason is that it was only added in Mustang (Java SE 6), whereas versions
 * 1.4 and 2.0 of the JMX API must be implementable on Tiger per our
 * commitments for JSR 255.  This is also why we suppress rawtypes warnings.
 */
@SuppressWarnings("rawtypes")
public interface RMIConnection extends Closeable, Remote {

  /**
   * <p>Returns the connection ID.  This string is different for
   * every open connection to a given RMI connector server.</p>
   *
   * @return the connection ID
   * @throws IOException if a general communication exception occurred.
   * @see RMIConnector#connect RMIConnector.connect
   */
  public String getConnectionId() throws IOException;

  /**
   * <p>Closes this connection.  On return from this method, the RMI
   * object implementing this interface is unexported, so further
   * remote calls to it will fail.</p>
   *
   * @throws IOException if the connection could not be closed, or the Remote object could not be
   * unexported, or there was a communication failure when transmitting the remote close request.
   */
  public void close() throws IOException;

  /**
   * Handles the method {@link
   * javax.management.MBeanServerConnection#createMBean(String,
   * ObjectName)}.
   *
   * @param className The class name of the MBean to be instantiated.
   * @param name The object name of the MBean. May be null.
   * @param delegationSubject The <code>Subject</code> containing the delegation principals or
   * <code>null</code> if the authentication principal is used instead.
   * @return An <code>ObjectInstance</code>, containing the <code>ObjectName</code> and the Java
   * class name of the newly instantiated MBean.  If the contained <code>ObjectName</code> is
   * <code>n</code>, the contained Java class name is <code>{@link #getMBeanInfo
   * getMBeanInfo(n)}.getClassName()</code>.
   * @throws ReflectionException Wraps a <code>java.lang.ClassNotFoundException</code> or a
   * <code>java.lang.Exception</code> that occurred when trying to invoke the MBean's constructor.
   * @throws InstanceAlreadyExistsException The MBean is already under the control of the MBean
   * server.
   * @throws MBeanRegistrationException The <code>preRegister</code> (<code>MBeanRegistration</code>
   * interface) method of the MBean has thrown an exception. The MBean will not be registered.
   * @throws MBeanException The constructor of the MBean has thrown an exception.
   * @throws NotCompliantMBeanException This class is not a JMX compliant MBean.
   * @throws RuntimeOperationsException Wraps a <code>java.lang.IllegalArgumentException</code>: The
   * className passed in parameter is null, the <code>ObjectName</code> passed in parameter contains
   * a pattern or no <code>ObjectName</code> is specified for the MBean.
   * @throws SecurityException if the client, or the delegated Subject if any, does not have
   * permission to perform this operation.
   * @throws IOException if a general communication exception occurred.
   */
  public ObjectInstance createMBean(String className,
      ObjectName name,
      Subject delegationSubject)
      throws
      ReflectionException,
      InstanceAlreadyExistsException,
      MBeanRegistrationException,
      MBeanException,
      NotCompliantMBeanException,
      IOException;

  /**
   * Handles the method {@link
   * javax.management.MBeanServerConnection#createMBean(String,
   * ObjectName, ObjectName)}.
   *
   * @param className The class name of the MBean to be instantiated.
   * @param name The object name of the MBean. May be null.
   * @param loaderName The object name of the class loader to be used.
   * @param delegationSubject The <code>Subject</code> containing the delegation principals or
   * <code>null</code> if the authentication principal is used instead.
   * @return An <code>ObjectInstance</code>, containing the <code>ObjectName</code> and the Java
   * class name of the newly instantiated MBean.  If the contained <code>ObjectName</code> is
   * <code>n</code>, the contained Java class name is <code>{@link #getMBeanInfo
   * getMBeanInfo(n)}.getClassName()</code>.
   * @throws ReflectionException Wraps a <code>java.lang.ClassNotFoundException</code> or a
   * <code>java.lang.Exception</code> that occurred when trying to invoke the MBean's constructor.
   * @throws InstanceAlreadyExistsException The MBean is already under the control of the MBean
   * server.
   * @throws MBeanRegistrationException The <code>preRegister</code> (<code>MBeanRegistration</code>
   * interface) method of the MBean has thrown an exception. The MBean will not be registered.
   * @throws MBeanException The constructor of the MBean has thrown an exception.
   * @throws NotCompliantMBeanException This class is not a JMX compliant MBean.
   * @throws InstanceNotFoundException The specified class loader is not registered in the MBean
   * server.
   * @throws RuntimeOperationsException Wraps a <code>java.lang.IllegalArgumentException</code>: The
   * className passed in parameter is null, the <code>ObjectName</code> passed in parameter contains
   * a pattern or no <code>ObjectName</code> is specified for the MBean.
   * @throws SecurityException if the client, or the delegated Subject if any, does not have
   * permission to perform this operation.
   * @throws IOException if a general communication exception occurred.
   */
  public ObjectInstance createMBean(String className,
      ObjectName name,
      ObjectName loaderName,
      Subject delegationSubject)
      throws
      ReflectionException,
      InstanceAlreadyExistsException,
      MBeanRegistrationException,
      MBeanException,
      NotCompliantMBeanException,
      InstanceNotFoundException,
      IOException;

  /**
   * Handles the method {@link
   * javax.management.MBeanServerConnection#createMBean(String,
   * ObjectName, Object[], String[])}.  The <code>Object[]</code>
   * parameter is wrapped in a <code>MarshalledObject</code>.
   *
   * @param className The class name of the MBean to be instantiated.
   * @param name The object name of the MBean. May be null.
   * @param params An array containing the parameters of the constructor to be invoked, encapsulated
   * into a <code>MarshalledObject</code>.  The encapsulated array can be null, equivalent to an
   * empty array.
   * @param signature An array containing the signature of the constructor to be invoked.  Can be
   * null, equivalent to an empty array.
   * @param delegationSubject The <code>Subject</code> containing the delegation principals or
   * <code>null</code> if the authentication principal is used instead.
   * @return An <code>ObjectInstance</code>, containing the <code>ObjectName</code> and the Java
   * class name of the newly instantiated MBean.  If the contained <code>ObjectName</code> is
   * <code>n</code>, the contained Java class name is <code>{@link #getMBeanInfo
   * getMBeanInfo(n)}.getClassName()</code>.
   * @throws ReflectionException Wraps a <code>java.lang.ClassNotFoundException</code> or a
   * <code>java.lang.Exception</code> that occurred when trying to invoke the MBean's constructor.
   * @throws InstanceAlreadyExistsException The MBean is already under the control of the MBean
   * server.
   * @throws MBeanRegistrationException The <code>preRegister</code> (<code>MBeanRegistration</code>
   * interface) method of the MBean has thrown an exception. The MBean will not be registered.
   * @throws MBeanException The constructor of the MBean has thrown an exception.
   * @throws NotCompliantMBeanException This class is not a JMX compliant MBean.
   * @throws RuntimeOperationsException Wraps a <code>java.lang.IllegalArgumentException</code>: The
   * className passed in parameter is null, the <code>ObjectName</code> passed in parameter contains
   * a pattern, or no <code>ObjectName</code> is specified for the MBean.
   * @throws SecurityException if the client, or the delegated Subject if any, does not have
   * permission to perform this operation.
   * @throws IOException if a general communication exception occurred.
   */
  public ObjectInstance createMBean(String className,
      ObjectName name,
      MarshalledObject params,
      String signature[],
      Subject delegationSubject)
      throws
      ReflectionException,
      InstanceAlreadyExistsException,
      MBeanRegistrationException,
      MBeanException,
      NotCompliantMBeanException,
      IOException;

  /**
   * Handles the method {@link
   * javax.management.MBeanServerConnection#createMBean(String,
   * ObjectName, ObjectName, Object[], String[])}.  The
   * <code>Object[]</code> parameter is wrapped in a
   * <code>MarshalledObject</code>.
   *
   * @param className The class name of the MBean to be instantiated.
   * @param name The object name of the MBean. May be null.
   * @param loaderName The object name of the class loader to be used.
   * @param params An array containing the parameters of the constructor to be invoked, encapsulated
   * into a <code>MarshalledObject</code>.  The encapsulated array can be null, equivalent to an
   * empty array.
   * @param signature An array containing the signature of the constructor to be invoked.  Can be
   * null, equivalent to an empty array.
   * @param delegationSubject The <code>Subject</code> containing the delegation principals or
   * <code>null</code> if the authentication principal is used instead.
   * @return An <code>ObjectInstance</code>, containing the <code>ObjectName</code> and the Java
   * class name of the newly instantiated MBean.  If the contained <code>ObjectName</code> is
   * <code>n</code>, the contained Java class name is <code>{@link #getMBeanInfo
   * getMBeanInfo(n)}.getClassName()</code>.
   * @throws ReflectionException Wraps a <code>java.lang.ClassNotFoundException</code> or a
   * <code>java.lang.Exception</code> that occurred when trying to invoke the MBean's constructor.
   * @throws InstanceAlreadyExistsException The MBean is already under the control of the MBean
   * server.
   * @throws MBeanRegistrationException The <code>preRegister</code> (<code>MBeanRegistration</code>
   * interface) method of the MBean has thrown an exception. The MBean will not be registered.
   * @throws MBeanException The constructor of the MBean has thrown an exception.
   * @throws NotCompliantMBeanException This class is not a JMX compliant MBean.
   * @throws InstanceNotFoundException The specified class loader is not registered in the MBean
   * server.
   * @throws RuntimeOperationsException Wraps a <code>java.lang.IllegalArgumentException</code>: The
   * className passed in parameter is null, the <code>ObjectName</code> passed in parameter contains
   * a pattern, or no <code>ObjectName</code> is specified for the MBean.
   * @throws SecurityException if the client, or the delegated Subject if any, does not have
   * permission to perform this operation.
   * @throws IOException if a general communication exception occurred.
   */
  public ObjectInstance createMBean(String className,
      ObjectName name,
      ObjectName loaderName,
      MarshalledObject params,
      String signature[],
      Subject delegationSubject)
      throws
      ReflectionException,
      InstanceAlreadyExistsException,
      MBeanRegistrationException,
      MBeanException,
      NotCompliantMBeanException,
      InstanceNotFoundException,
      IOException;

  /**
   * Handles the method
   * {@link javax.management.MBeanServerConnection#unregisterMBean(ObjectName)}.
   *
   * @param name The object name of the MBean to be unregistered.
   * @param delegationSubject The <code>Subject</code> containing the delegation principals or
   * <code>null</code> if the authentication principal is used instead.
   * @throws InstanceNotFoundException The MBean specified is not registered in the MBean server.
   * @throws MBeanRegistrationException The preDeregister ((<code>MBeanRegistration</code>
   * interface) method of the MBean has thrown an exception.
   * @throws RuntimeOperationsException Wraps a <code>java.lang.IllegalArgumentException</code>: The
   * object name in parameter is null or the MBean you are when trying to unregister is the {@link
   * javax.management.MBeanServerDelegate MBeanServerDelegate} MBean.
   * @throws SecurityException if the client, or the delegated Subject if any, does not have
   * permission to perform this operation.
   * @throws IOException if a general communication exception occurred.
   */
  public void unregisterMBean(ObjectName name, Subject delegationSubject)
      throws
      InstanceNotFoundException,
      MBeanRegistrationException,
      IOException;

  /**
   * Handles the method
   * {@link javax.management.MBeanServerConnection#getObjectInstance(ObjectName)}.
   *
   * @param name The object name of the MBean.
   * @param delegationSubject The <code>Subject</code> containing the delegation principals or
   * <code>null</code> if the authentication principal is used instead.
   * @return The <code>ObjectInstance</code> associated with the MBean specified by <var>name</var>.
   * The contained <code>ObjectName</code> is <code>name</code> and the contained class name is
   * <code>{@link #getMBeanInfo getMBeanInfo(name)}.getClassName()</code>.
   * @throws InstanceNotFoundException The MBean specified is not registered in the MBean server.
   * @throws RuntimeOperationsException Wraps a <code>java.lang.IllegalArgumentException</code>: The
   * object name in parameter is null.
   * @throws SecurityException if the client, or the delegated Subject if any, does not have
   * permission to perform this operation.
   * @throws IOException if a general communication exception occurred.
   */
  public ObjectInstance getObjectInstance(ObjectName name,
      Subject delegationSubject)
      throws InstanceNotFoundException, IOException;

  /**
   * Handles the method {@link
   * javax.management.MBeanServerConnection#queryMBeans(ObjectName,
   * QueryExp)}.  The <code>QueryExp</code> is wrapped in a
   * <code>MarshalledObject</code>.
   *
   * @param name The object name pattern identifying the MBeans to be retrieved. If null or no
   * domain and key properties are specified, all the MBeans registered will be retrieved.
   * @param query The query expression to be applied for selecting MBeans, encapsulated into a
   * <code>MarshalledObject</code>. If the <code>MarshalledObject</code> encapsulates a null value
   * no query expression will be applied for selecting MBeans.
   * @param delegationSubject The <code>Subject</code> containing the delegation principals or
   * <code>null</code> if the authentication principal is used instead.
   * @return A set containing the <code>ObjectInstance</code> objects for the selected MBeans.  If
   * no MBean satisfies the query an empty list is returned.
   * @throws SecurityException if the client, or the delegated Subject if any, does not have
   * permission to perform this operation.
   * @throws IOException if a general communication exception occurred.
   */
  public Set<ObjectInstance>
  queryMBeans(ObjectName name,
      MarshalledObject query,
      Subject delegationSubject)
      throws IOException;

  /**
   * Handles the method {@link
   * javax.management.MBeanServerConnection#queryNames(ObjectName,
   * QueryExp)}.  The <code>QueryExp</code> is wrapped in a
   * <code>MarshalledObject</code>.
   *
   * @param name The object name pattern identifying the MBean names to be retrieved. If null or no
   * domain and key properties are specified, the name of all registered MBeans will be retrieved.
   * @param query The query expression to be applied for selecting MBeans, encapsulated into a
   * <code>MarshalledObject</code>. If the <code>MarshalledObject</code> encapsulates a null value
   * no query expression will be applied for selecting MBeans.
   * @param delegationSubject The <code>Subject</code> containing the delegation principals or
   * <code>null</code> if the authentication principal is used instead.
   * @return A set containing the ObjectNames for the MBeans selected.  If no MBean satisfies the
   * query, an empty list is returned.
   * @throws SecurityException if the client, or the delegated Subject if any, does not have
   * permission to perform this operation.
   * @throws IOException if a general communication exception occurred.
   */
  public Set<ObjectName>
  queryNames(ObjectName name,
      MarshalledObject query,
      Subject delegationSubject)
      throws IOException;

  /**
   * Handles the method
   * {@link javax.management.MBeanServerConnection#isRegistered(ObjectName)}.
   *
   * @param name The object name of the MBean to be checked.
   * @param delegationSubject The <code>Subject</code> containing the delegation principals or
   * <code>null</code> if the authentication principal is used instead.
   * @return True if the MBean is already registered in the MBean server, false otherwise.
   * @throws RuntimeOperationsException Wraps a <code>java.lang.IllegalArgumentException</code>: The
   * object name in parameter is null.
   * @throws SecurityException if the client, or the delegated Subject if any, does not have
   * permission to perform this operation.
   * @throws IOException if a general communication exception occurred.
   */
  public boolean isRegistered(ObjectName name, Subject delegationSubject)
      throws IOException;

  /**
   * Handles the method
   * {@link javax.management.MBeanServerConnection#getMBeanCount()}.
   *
   * @param delegationSubject The <code>Subject</code> containing the delegation principals or
   * <code>null</code> if the authentication principal is used instead.
   * @return the number of MBeans registered.
   * @throws SecurityException if the client, or the delegated Subject if any, does not have
   * permission to perform this operation.
   * @throws IOException if a general communication exception occurred.
   */
  public Integer getMBeanCount(Subject delegationSubject)
      throws IOException;

  /**
   * Handles the method {@link
   * javax.management.MBeanServerConnection#getAttribute(ObjectName,
   * String)}.
   *
   * @param name The object name of the MBean from which the attribute is to be retrieved.
   * @param attribute A String specifying the name of the attribute to be retrieved.
   * @param delegationSubject The <code>Subject</code> containing the delegation principals or
   * <code>null</code> if the authentication principal is used instead.
   * @return The value of the retrieved attribute.
   * @throws AttributeNotFoundException The attribute specified is not accessible in the MBean.
   * @throws MBeanException Wraps an exception thrown by the MBean's getter.
   * @throws InstanceNotFoundException The MBean specified is not registered in the MBean server.
   * @throws ReflectionException Wraps a <code>java.lang.Exception</code> thrown when trying to
   * invoke the getter.
   * @throws RuntimeOperationsException Wraps a <code>java.lang.IllegalArgumentException</code>: The
   * object name in parameter is null or the attribute in parameter is null.
   * @throws RuntimeMBeanException Wraps a runtime exception thrown by the MBean's getter.
   * @throws SecurityException if the client, or the delegated Subject if any, does not have
   * permission to perform this operation.
   * @throws IOException if a general communication exception occurred.
   * @see #setAttribute
   */
  public Object getAttribute(ObjectName name,
      String attribute,
      Subject delegationSubject)
      throws
      MBeanException,
      AttributeNotFoundException,
      InstanceNotFoundException,
      ReflectionException,
      IOException;

  /**
   * Handles the method {@link
   * javax.management.MBeanServerConnection#getAttributes(ObjectName,
   * String[])}.
   *
   * @param name The object name of the MBean from which the attributes are retrieved.
   * @param attributes A list of the attributes to be retrieved.
   * @param delegationSubject The <code>Subject</code> containing the delegation principals or
   * <code>null</code> if the authentication principal is used instead.
   * @return The list of the retrieved attributes.
   * @throws InstanceNotFoundException The MBean specified is not registered in the MBean server.
   * @throws ReflectionException An exception occurred when trying to invoke the getAttributes
   * method of a Dynamic MBean.
   * @throws RuntimeOperationsException Wrap a <code>java.lang.IllegalArgumentException</code>: The
   * object name in parameter is null or attributes in parameter is null.
   * @throws SecurityException if the client, or the delegated Subject if any, does not have
   * permission to perform this operation.
   * @throws IOException if a general communication exception occurred.
   * @see #setAttributes
   */
  public AttributeList getAttributes(ObjectName name,
      String[] attributes,
      Subject delegationSubject)
      throws
      InstanceNotFoundException,
      ReflectionException,
      IOException;

  /**
   * Handles the method {@link
   * javax.management.MBeanServerConnection#setAttribute(ObjectName,
   * Attribute)}.  The <code>Attribute</code> parameter is wrapped
   * in a <code>MarshalledObject</code>.
   *
   * @param name The name of the MBean within which the attribute is to be set.
   * @param attribute The identification of the attribute to be set and the value it is to be set
   * to, encapsulated into a <code>MarshalledObject</code>.
   * @param delegationSubject The <code>Subject</code> containing the delegation principals or
   * <code>null</code> if the authentication principal is used instead.
   * @throws InstanceNotFoundException The MBean specified is not registered in the MBean server.
   * @throws AttributeNotFoundException The attribute specified is not accessible in the MBean.
   * @throws InvalidAttributeValueException The value specified for the attribute is not valid.
   * @throws MBeanException Wraps an exception thrown by the MBean's setter.
   * @throws ReflectionException Wraps a <code>java.lang.Exception</code> thrown when trying to
   * invoke the setter.
   * @throws RuntimeOperationsException Wraps a <code>java.lang.IllegalArgumentException</code>: The
   * object name in parameter is null or the attribute in parameter is null.
   * @throws SecurityException if the client, or the delegated Subject if any, does not have
   * permission to perform this operation.
   * @throws IOException if a general communication exception occurred.
   * @see #getAttribute
   */
  public void setAttribute(ObjectName name,
      MarshalledObject attribute,
      Subject delegationSubject)
      throws
      InstanceNotFoundException,
      AttributeNotFoundException,
      InvalidAttributeValueException,
      MBeanException,
      ReflectionException,
      IOException;

  /**
   * Handles the method {@link
   * javax.management.MBeanServerConnection#setAttributes(ObjectName,
   * AttributeList)}.  The <code>AttributeList</code> parameter is
   * wrapped in a <code>MarshalledObject</code>.
   *
   * @param name The object name of the MBean within which the attributes are to be set.
   * @param attributes A list of attributes: The identification of the attributes to be set and the
   * values they are to be set to, encapsulated into a <code>MarshalledObject</code>.
   * @param delegationSubject The <code>Subject</code> containing the delegation principals or
   * <code>null</code> if the authentication principal is used instead.
   * @return The list of attributes that were set, with their new values.
   * @throws InstanceNotFoundException The MBean specified is not registered in the MBean server.
   * @throws ReflectionException An exception occurred when trying to invoke the getAttributes
   * method of a Dynamic MBean.
   * @throws RuntimeOperationsException Wraps a <code>java.lang.IllegalArgumentException</code>: The
   * object name in parameter is null or attributes in parameter is null.
   * @throws SecurityException if the client, or the delegated Subject if any, does not have
   * permission to perform this operation.
   * @throws IOException if a general communication exception occurred.
   * @see #getAttributes
   */
  public AttributeList setAttributes(ObjectName name,
      MarshalledObject attributes,
      Subject delegationSubject)
      throws
      InstanceNotFoundException,
      ReflectionException,
      IOException;

  /**
   * Handles the method {@link
   * javax.management.MBeanServerConnection#invoke(ObjectName,
   * String, Object[], String[])}.  The <code>Object[]</code>
   * parameter is wrapped in a <code>MarshalledObject</code>.
   *
   * @param name The object name of the MBean on which the method is to be invoked.
   * @param operationName The name of the operation to be invoked.
   * @param params An array containing the parameters to be set when the operation is invoked,
   * encapsulated into a <code>MarshalledObject</code>.  The encapsulated array can be null,
   * equivalent to an empty array.
   * @param signature An array containing the signature of the operation. The class objects will be
   * loaded using the same class loader as the one used for loading the MBean on which the operation
   * was invoked.  Can be null, equivalent to an empty array.
   * @param delegationSubject The <code>Subject</code> containing the delegation principals or
   * <code>null</code> if the authentication principal is used instead.
   * @return The object returned by the operation, which represents the result of invoking the
   * operation on the MBean specified.
   * @throws InstanceNotFoundException The MBean specified is not registered in the MBean server.
   * @throws MBeanException Wraps an exception thrown by the MBean's invoked method.
   * @throws ReflectionException Wraps a <code>java.lang.Exception</code> thrown while trying to
   * invoke the method.
   * @throws SecurityException if the client, or the delegated Subject if any, does not have
   * permission to perform this operation.
   * @throws IOException if a general communication exception occurred.
   * @throws RuntimeOperationsException Wraps an {@link IllegalArgumentException} when
   * <code>name</code> or <code>operationName</code> is null.
   */
  public Object invoke(ObjectName name,
      String operationName,
      MarshalledObject params,
      String signature[],
      Subject delegationSubject)
      throws
      InstanceNotFoundException,
      MBeanException,
      ReflectionException,
      IOException;

  /**
   * Handles the method
   * {@link javax.management.MBeanServerConnection#getDefaultDomain()}.
   *
   * @param delegationSubject The <code>Subject</code> containing the delegation principals or
   * <code>null</code> if the authentication principal is used instead.
   * @return the default domain.
   * @throws SecurityException if the client, or the delegated Subject if any, does not have
   * permission to perform this operation.
   * @throws IOException if a general communication exception occurred.
   */
  public String getDefaultDomain(Subject delegationSubject)
      throws IOException;

  /**
   * Handles the method
   * {@link javax.management.MBeanServerConnection#getDomains()}.
   *
   * @param delegationSubject The <code>Subject</code> containing the delegation principals or
   * <code>null</code> if the authentication principal is used instead.
   * @return the list of domains.
   * @throws SecurityException if the client, or the delegated Subject if any, does not have
   * permission to perform this operation.
   * @throws IOException if a general communication exception occurred.
   */
  public String[] getDomains(Subject delegationSubject)
      throws IOException;

  /**
   * Handles the method
   * {@link javax.management.MBeanServerConnection#getMBeanInfo(ObjectName)}.
   *
   * @param name The name of the MBean to analyze
   * @param delegationSubject The <code>Subject</code> containing the delegation principals or
   * <code>null</code> if the authentication principal is used instead.
   * @return An instance of <code>MBeanInfo</code> allowing the retrieval of all attributes and
   * operations of this MBean.
   * @throws IntrospectionException An exception occurred during introspection.
   * @throws InstanceNotFoundException The MBean specified was not found.
   * @throws ReflectionException An exception occurred when trying to invoke the getMBeanInfo of a
   * Dynamic MBean.
   * @throws SecurityException if the client, or the delegated Subject if any, does not have
   * permission to perform this operation.
   * @throws IOException if a general communication exception occurred.
   * @throws RuntimeOperationsException Wraps a <code>java.lang.IllegalArgumentException</code>: The
   * object name in parameter is null.
   */
  public MBeanInfo getMBeanInfo(ObjectName name, Subject delegationSubject)
      throws
      InstanceNotFoundException,
      IntrospectionException,
      ReflectionException,
      IOException;

  /**
   * Handles the method {@link
   * javax.management.MBeanServerConnection#isInstanceOf(ObjectName,
   * String)}.
   *
   * @param name The <code>ObjectName</code> of the MBean.
   * @param className The name of the class.
   * @param delegationSubject The <code>Subject</code> containing the delegation principals or
   * <code>null</code> if the authentication principal is used instead.
   * @return true if the MBean specified is an instance of the specified class according to the
   * rules above, false otherwise.
   * @throws InstanceNotFoundException The MBean specified is not registered in the MBean server.
   * @throws SecurityException if the client, or the delegated Subject if any, does not have
   * permission to perform this operation.
   * @throws IOException if a general communication exception occurred.
   * @throws RuntimeOperationsException Wraps a <code>java.lang.IllegalArgumentException</code>: The
   * object name in parameter is null.
   */
  public boolean isInstanceOf(ObjectName name,
      String className,
      Subject delegationSubject)
      throws InstanceNotFoundException, IOException;

  /**
   * Handles the method {@link
   * javax.management.MBeanServerConnection#addNotificationListener(ObjectName,
   * ObjectName, NotificationFilter, Object)}.  The
   * <code>NotificationFilter</code> parameter is wrapped in a
   * <code>MarshalledObject</code>.  The <code>Object</code>
   * (handback) parameter is also wrapped in a
   * <code>MarshalledObject</code>.
   *
   * @param name The name of the MBean on which the listener should be added.
   * @param listener The object name of the listener which will handle the notifications emitted by
   * the registered MBean.
   * @param filter The filter object, encapsulated into a <code>MarshalledObject</code>. If filter
   * encapsulated in the <code>MarshalledObject</code> has a null value, no filtering will be
   * performed before handling notifications.
   * @param handback The context to be sent to the listener when a notification is emitted,
   * encapsulated into a <code>MarshalledObject</code>.
   * @param delegationSubject The <code>Subject</code> containing the delegation principals or
   * <code>null</code> if the authentication principal is used instead.
   * @throws InstanceNotFoundException The MBean name of the notification listener or of the
   * notification broadcaster does not match any of the registered MBeans.
   * @throws RuntimeOperationsException Wraps an {@link IllegalArgumentException}.  The MBean named
   * by <code>listener</code> exists but does not implement the {@link
   * javax.management.NotificationListener} interface, or <code>name</code> or <code>listener</code>
   * is null.
   * @throws SecurityException if the client, or the delegated Subject if any, does not have
   * permission to perform this operation.
   * @throws IOException if a general communication exception occurred.
   * @see #removeNotificationListener(ObjectName, ObjectName, Subject)
   * @see #removeNotificationListener(ObjectName, ObjectName, MarshalledObject, MarshalledObject,
   * Subject)
   */
  public void addNotificationListener(ObjectName name,
      ObjectName listener,
      MarshalledObject filter,
      MarshalledObject handback,
      Subject delegationSubject)
      throws InstanceNotFoundException, IOException;

  /**
   * Handles the method {@link
   * javax.management.MBeanServerConnection#removeNotificationListener(ObjectName,
   * ObjectName)}.
   *
   * @param name The name of the MBean on which the listener should be removed.
   * @param listener The object name of the listener to be removed.
   * @param delegationSubject The <code>Subject</code> containing the delegation principals or
   * <code>null</code> if the authentication principal is used instead.
   * @throws InstanceNotFoundException The MBean name provided does not match any of the registered
   * MBeans.
   * @throws ListenerNotFoundException The listener is not registered in the MBean.
   * @throws SecurityException if the client, or the delegated Subject if any, does not have
   * permission to perform this operation.
   * @throws IOException if a general communication exception occurred.
   * @throws RuntimeOperationsException Wraps an {@link IllegalArgumentException} when
   * <code>name</code> or <code>listener</code> is null.
   * @see #addNotificationListener
   */
  public void removeNotificationListener(ObjectName name,
      ObjectName listener,
      Subject delegationSubject)
      throws
      InstanceNotFoundException,
      ListenerNotFoundException,
      IOException;

  /**
   * Handles the method {@link
   * javax.management.MBeanServerConnection#removeNotificationListener(ObjectName,
   * ObjectName, NotificationFilter, Object)}.  The
   * <code>NotificationFilter</code> parameter is wrapped in a
   * <code>MarshalledObject</code>.  The <code>Object</code>
   * parameter is also wrapped in a <code>MarshalledObject</code>.
   *
   * @param name The name of the MBean on which the listener should be removed.
   * @param listener A listener that was previously added to this MBean.
   * @param filter The filter that was specified when the listener was added, encapsulated into a
   * <code>MarshalledObject</code>.
   * @param handback The handback that was specified when the listener was added, encapsulated into
   * a <code>MarshalledObject</code>.
   * @param delegationSubject The <code>Subject</code> containing the delegation principals or
   * <code>null</code> if the authentication principal is used instead.
   * @throws InstanceNotFoundException The MBean name provided does not match any of the registered
   * MBeans.
   * @throws ListenerNotFoundException The listener is not registered in the MBean, or it is not
   * registered with the given filter and handback.
   * @throws SecurityException if the client, or the delegated Subject if any, does not have
   * permission to perform this operation.
   * @throws IOException if a general communication exception occurred.
   * @throws RuntimeOperationsException Wraps an {@link IllegalArgumentException} when
   * <code>name</code> or <code>listener</code> is null.
   * @see #addNotificationListener
   */
  public void removeNotificationListener(ObjectName name,
      ObjectName listener,
      MarshalledObject filter,
      MarshalledObject handback,
      Subject delegationSubject)
      throws
      InstanceNotFoundException,
      ListenerNotFoundException,
      IOException;

  // Special Handling of Notifications -------------------------------------

  /**
   * <p>Handles the method {@link
   * javax.management.MBeanServerConnection#addNotificationListener(ObjectName,
   * NotificationListener, NotificationFilter, Object)}.</p>
   *
   * <p>Register for notifications from the given MBeans that match
   * the given filters.  The remote client can subsequently retrieve
   * the notifications using the {@link #fetchNotifications
   * fetchNotifications} method.</p>
   *
   * <p>For each listener, the original
   * <code>NotificationListener</code> and <code>handback</code> are
   * kept on the client side; in order for the client to be able to
   * identify them, the server generates and returns a unique
   * <code>listenerID</code>.  This <code>listenerID</code> is
   * forwarded with the <code>Notifications</code> to the remote
   * client.</p>
   *
   * <p>If any one of the given (name, filter) pairs cannot be
   * registered, then the operation fails with an exception, and no
   * names or filters are registered.</p>
   *
   * @param names the <code>ObjectNames</code> identifying the MBeans emitting the Notifications.
   * @param filters an array of marshalled representations of the <code>NotificationFilters</code>.
   * Elements of this array can be null.
   * @param delegationSubjects the <code>Subjects</code> on behalf of which the listeners are being
   * added.  Elements of this array can be null.  Also, the <code>delegationSubjects</code>
   * parameter itself can be null, which is equivalent to an array of null values with the same size
   * as the <code>names</code> and <code>filters</code> arrays.
   * @return an array of <code>listenerIDs</code> identifying the local listeners.  This array has
   * the same number of elements as the parameters.
   * @throws IllegalArgumentException if <code>names</code> or <code>filters</code> is null, or if
   * <code>names</code> contains a null element, or if the three arrays do not all have the same
   * size.
   * @throws ClassCastException if one of the elements of <code>filters</code> unmarshalls as a
   * non-null object that is not a <code>NotificationFilter</code>.
   * @throws InstanceNotFoundException if one of the <code>names</code> does not correspond to any
   * registered MBean.
   * @throws SecurityException if, for one of the MBeans, the client, or the delegated Subject if
   * any, does not have permission to add a listener.
   * @throws IOException if a general communication exception occurred.
   */
  public Integer[] addNotificationListeners(ObjectName[] names,
      MarshalledObject[] filters,
      Subject[] delegationSubjects)
      throws InstanceNotFoundException, IOException;

  /**
   * <p>Handles the {@link javax.management.MBeanServerConnection#removeNotificationListener(ObjectName, NotificationListener)
   * removeNotificationListener(ObjectName, NotificationListener)} and {@link
   * javax.management.MBeanServerConnection#removeNotificationListener(ObjectName, NotificationListener, NotificationFilter, Object)
   * removeNotificationListener(ObjectName, NotificationListener, NotificationFilter, Object)}
   * methods.</p>
   *
   * <p>This method removes one or more <code>NotificationListener</code>s from a given MBean in the
   * MBean server.</p>
   *
   * <p>The <code>NotificationListeners</code> are identified by the IDs which were returned by the
   * {@link #addNotificationListeners(ObjectName[], MarshalledObject[], Subject[])} method.</p>
   *
   * @param name the <code>ObjectName</code> identifying the MBean emitting the Notifications.
   * @param listenerIDs the list of the IDs corresponding to the listeners to remove.
   * @param delegationSubject The <code>Subject</code> containing the delegation principals or
   * <code>null</code> if the authentication principal is used instead.
   * @throws InstanceNotFoundException if the given <code>name</code> does not correspond to any
   * registered MBean.
   * @throws ListenerNotFoundException if one of the listeners was not found on the server side.
   * This exception can happen if the MBean discarded a listener for some reason other than a call
   * to <code>MBeanServer.removeNotificationListener</code>.
   * @throws SecurityException if the client, or the delegated Subject if any, does not have
   * permission to remove the listeners.
   * @throws IOException if a general communication exception occurred.
   * @throws IllegalArgumentException if <code>ObjectName</code> or <code>listenerIds</code> is null
   * or if <code>listenerIds</code> contains a null element.
   */
  public void removeNotificationListeners(ObjectName name,
      Integer[] listenerIDs,
      Subject delegationSubject)
      throws
      InstanceNotFoundException,
      ListenerNotFoundException,
      IOException;

  /**
   * <p>Retrieves notifications from the connector server.  This
   * method can block until there is at least one notification or
   * until the specified timeout is reached.  The method can also
   * return at any time with zero notifications.</p>
   *
   * <p>A notification can be included in the result if its sequence
   * number is no less than <code>clientSequenceNumber</code> and
   * this client has registered at least one listener for the MBean
   * generating the notification, with a filter that accepts the
   * notification.  Each listener that is interested in the
   * notification is identified by an Integer ID that was returned
   * by {@link #addNotificationListeners(ObjectName[],
   * MarshalledObject[], Subject[])}.</p>
   *
   * @param clientSequenceNumber the first sequence number that the client is interested in.  If
   * negative, it is interpreted as meaning the sequence number that the next notification will
   * have.
   * @param maxNotifications the maximum number of different notifications to return.  The
   * <code>TargetedNotification</code> array in the returned <code>NotificationResult</code> can
   * have more elements than this if the same notification appears more than once.  The behavior is
   * unspecified if this parameter is negative.
   * @param timeout the maximum time in milliseconds to wait for a notification to arrive.  This can
   * be 0 to indicate that the method should not wait if there are no notifications, but should
   * return at once.  It can be <code>Long.MAX_VALUE</code> to indicate that there is no timeout.
   * The behavior is unspecified if this parameter is negative.
   * @return A <code>NotificationResult</code>.
   * @throws IOException if a general communication exception occurred.
   */
  public NotificationResult fetchNotifications(long clientSequenceNumber,
      int maxNotifications,
      long timeout)
      throws IOException;
}
